home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / utilities / exdat100.lha / xd / README < prev    next >
Encoding:
Text File  |  1994-01-28  |  5.9 KB  |  197 lines
  1.     The EXTernal DATA package
  2.     -------------------------
  3.  
  4.                        Cédric BEUST (beust@sophia.inria.fr)
  5.  
  6.  
  7.  
  8. This linkable library will let you dump the internal structures of
  9. a program to a file, and the other way around, very easily. The file
  10. created is an IFF one, so you can also see this library as a layer
  11. above iffparse that will hide all its complexity behind a friendly
  12. API (which iffparse lacks :-)).
  13.  
  14. ExtData ensures a maximum compatibility between different versions of
  15. the same file, since it uses named records to store its information.
  16. Its main use is for the "Open", "Save", "Save as..." menus that
  17. any Amiga-application should have.
  18.  
  19. For example, here is a sample code to write a file :
  20.  
  21.       xd = xd_Open("test", XD_WRITE, "xdtest");
  22.       if (xd) {
  23.      xd_DeclareField(xd, "name", XD_STRING);
  24.      xd_DeclareField(xd, "age", XD_INTEGER);
  25.      xd_DeclareField(xd, "height", XD_INTEGER);
  26.  
  27.      xd_AssignField(xd, "name", "Cedric");
  28.      xd_AssignField(xd, "age", & age);
  29.      xd_AssignField(xd, "height", & height);
  30.      xd_WriteRecord(xd);
  31.  
  32.          xd_Close(xd);
  33.       }
  34.  
  35. and to read it :
  36.  
  37.       xd = xd_Open("test", XD_READ, "xdtest");
  38.       if (xd) {
  39.      while (xd_NextRecord(xd)) {
  40.         xd_ReadField(xd, "age", XD_INTEGER, & a);
  41.         xd_ReadField(xd, "name", XD_STRING, & name);
  42.         xd_ReadField(xd, "height", XD_STRING, & h);
  43.         printf("read name=%s age=%d height=%d\n", name, a, h);
  44.      }
  45.      xd_Close(xd);
  46.       }
  47.  
  48. Suppose this version of your file is 1.0. Then your application is bumped
  49. to version 1.1 with the effect of adding a new field to your internal
  50. structures (say "sex").
  51.  
  52. 1.0 reads 1.1 file -> works fine (ascending compatibility)
  53. 1.1 reads 1.0 file -> "can't find field sex" and set it to a default value
  54.  
  55. Another advantage is that fields can be read in any order (since they
  56. are "named").
  57.  
  58. Additionally, ExtData will let you define some "shared" information
  59. in the file (e.g. the application to which it belongs, or its version
  60. number).
  61.  
  62.  
  63.  
  64.     The distribution
  65.     ----------------
  66.  
  67. The library is in xd.c and the compilation will output a linked
  68. library called xd.lib.
  69.  
  70. xdtest is a small test program. Type "xdtest" to write an ExtData file
  71. called "test" and then type "xdtest 1" to read it.
  72.  
  73. All your program has to do in order to use ExtData is to include xd.h
  74. and add xd.lib to the list of linked libraries it uses (see smakefile).
  75.  
  76.  
  77.     Bugs and limitations
  78.     --------------------
  79.  
  80. . xd is very verbose for errors (the source is filled with
  81. fprintf(stderr, ...)), so it is not appropriate for Workbench applications
  82. unless they have some stderr. I'm thinking about giving an easy way
  83. to control this (e.g. keep it verbose for debugging purposes, but
  84. shutting it off for distribution with a single define)
  85.  
  86. . xd doesn't solve the problem of nested structures. But without xd,
  87. the problem is even worse, so... Anyway, I'll try to come up with
  88. a solution.
  89.  
  90.  
  91.     Miscellaneous considerations
  92.     ----------------------------
  93.  
  94. There are two reasons why I wrote ExtData :
  95.  
  96. . When you develop an application, you have more important things
  97. to think about than juggling with iffparse. Hopefully, the ExtData
  98. user will be able to focus on the specific aspects of their application
  99. and let ExtData do the dirty work. At least during the debugging process.
  100. When the application "stands", they can always decide to rip ExtData off
  101. it in order to have more control on the way files are Read/Writted, or
  102. to cut off size (although ExtData is rather small).
  103.  
  104. . ExtData seems to provide a clean way to advertise the format your application
  105. is using, making transfers to and from other application easy. For example,
  106. xdtest uses the following format :
  107.  
  108. Shared:
  109.   Type: "xdtest"
  110. Information:
  111.   "info" ("General information" in the example)
  112. Fields:
  113.   "name" (string)
  114.   "age" (integer)
  115.   "height" (integer)
  116.  
  117. With this mere information, any application using ExtData will be able to reread
  118. files saved by xdtest.
  119.  
  120.     Errors
  121.     ------
  122.  
  123. Most functions that can fail will return an int. 0 will mean success.
  124. In case of failure, the error code can be retrieved with xd_ErrorCode()
  125. and a string indicating the error with xd_ErrorString().
  126.  
  127.  
  128.     API and List of functions
  129.     -------------------------
  130.  
  131. All functions start with xd_.
  132. All defined types start with Xd_.
  133.  
  134. The API can be found in xd.h where it is abundantly commented.
  135.  
  136. xd_Init
  137. xd_Uninit
  138. xd_Open
  139. xd_Close
  140. xd_ErrorCode
  141. xd_ErrorString
  142. xd_DeclareAuthor
  143. xd_DeclareApplication
  144. xd_DeclareVersion
  145. xd_DeclareDate
  146. xd_ReadType
  147. xd_ReadApplication
  148. xd_ReadAuthor
  149. xd_ReadDate
  150. xd_ReadVersion
  151. xd_DeclareSharedString
  152. xd_ReadSharedString
  153. xd_DeclareField
  154. xd_AssignField
  155. xd_WriteRecord
  156. xd_NextRecord
  157. xd_EndOfFile
  158. xd_ReadField
  159. xd_Free
  160.  
  161.  
  162.     The internal format
  163.     -------------------
  164.  
  165. An ExtData file is split in two parts : a "common" part and the content
  166. of the data itself. The common part can be seen as the header.
  167.  
  168. The common part contains three different sections :
  169. - XINF   constant information. There are five slots here, of which
  170.          only the first one is mandatory : type, application, author,
  171.          version and date.
  172.          Writing : xd_Open(), xd_DeclareApplication(), xd_DeclareAuthor(),
  173.                    xd_DeclareVersion() and xd_DeclareDate().
  174.          Reading : xd_ReadType(), xd_ReadApplication(), xd_ReadAuthor(),
  175.                    xd_ReadVersion(), xd_ReadDate()
  176.  
  177. - XFIE   the name of each field your records contain, with their
  178.          type.
  179.          Writing : xd_DeclareField().
  180.          Reading : automatically performed by xd_Open() in XD_READ mode
  181.  
  182. - XUSE   if you need your file to contain additional data that wouldn't
  183.          fit in the previous categories, you can use this section to store
  184.          association values (key/value).
  185.          Writing : xd_DeclareSharedString()
  186.          Reading : xd_ReadSharedString()
  187.  
  188. The data itself is stored in an XCON chunk. Each record is introduced by
  189. an XREC chunk followed by the value of each field (which are looked up
  190. between those read in the XFIE chunk).
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.